<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>bmqt_uri Component</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="bdedox.css" rel="stylesheet" type="text/css"/>
    <style>
      div.hanging {
        padding-left: 0.75in;
        text-indent: -0.50in;
      }
      div.unhanging {
        text-indent:     0in;
      }
      a.glossary {
        font-weight: bold;
        font-style: italic;
      }
    </style>
</head>
<!--
<body onload='searchBox.OnSelectItem(0);'>
-->
<body>

<table border=2 cellspacing=0 cellpadding=0 align=center>
<tr>
 <td valign=top align=center>
 <p align=center><b><i>Quick Links:</i></b></p>
 </td>
 <td valign=top align=center>
 <p align=center>
<a class="qindex" href="group__bmqa.html" target="_blank">bmqa</a> | <a class="qindex" href="group__bmqpi.html" target="_blank">bmqpi</a> | <a class="qindex" href="group__bmqt.html" target="_blank">bmqt</a>
 </td>
 </tr>
 </table>

  </div>
<!-- Generated by Doxygen 1.7.1 -->
<div class="navigation" id="top">
  <div class="tabs">
    <ul class="tablist">
      <li><a href="components.html"><span>Main&nbsp;Page</span></a></li>
      <li><a href="components.html"><span>Components</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div class="header">
  <div class="headertitle">
<h1>Component bmqt_uri<br/>
<small>
[<a class="el" href="group__bmqt.html">Package bmqt</a>]</small>
</h1>  </div>
</div>
<div class="contents">

<p>Provide value-semantic type and utilities for a BlazingMQ queue.  
<a href="#_details">More...</a></p>
<table class="memberdecls">
</table>
<dl class="user"><dt><b>Outline</b></dt><dd><ul>
<li>
<a href="#1">Purpose</a> </li>
<li>
<a href="#2">Classes</a> </li>
<li>
<a href="#3">Description</a> <ul>
<li>
<a href="#3.1">URI format</a> </li>
<li>
<a href="#3.2">Usage Example 1</a> </li>
<li>
<a href="#3.3">Usage Example 2</a> </li>
</ul>
</li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="purpose"></a> <a class="anchor" id="1"></a> </dd></dl>
<dl class="user"><dt><b>Purpose: </b></dt><dd>Provide value-semantic type and utilities for a BlazingMQ queue URI. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="classes"></a> <a class="anchor" id="2"></a> </dd></dl>
<dl class="user"><dt><b>Classes: </b></dt><dd><table class="doxtable">
<tr>
<td><a class="el" href="classbmqt_1_1Uri.html">bmqt::Uri</a>  </td><td>value-semantic type representing a URI  </td></tr>
<tr>
<td><a class="el" href="structbmqt_1_1UriParser.html">bmqt::UriParser</a>  </td><td>utility to parse a string into a URI  </td></tr>
<tr>
<td><a class="el" href="classbmqt_1_1UriBuilder.html">bmqt::UriBuilder</a>  </td><td>builder mechanism to create a URI  </td></tr>
</table>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="description"></a> <a class="anchor" id="3"></a> </dd></dl>
<dl class="user"><dt><b>Description: </b></dt><dd>This component provides a value-semantic type, <code><a class="el" href="classbmqt_1_1Uri.html">bmqt::Uri</a></code> representing a URI for a BlazingMQ queue. A <code>bmqt:Uri</code> can be built by parsing from a string representation, using the <code><a class="el" href="structbmqt_1_1UriParser.html">bmqt::UriParser</a></code>, or built using the <code><a class="el" href="classbmqt_1_1UriBuilder.html">bmqt::UriBuilder</a></code>. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd>---------- <a href="https://tools.ietf.org/html/rfc3986">https://tools.ietf.org/html/rfc3986</a> </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="uri_format"></a> <a class="anchor" id="description.uri_format"></a> <a class="anchor" id="3.1"></a> </dd></dl>
<dl class="user"><dt><b>URI format: </b></dt><dd>In a nutshell, a URI representing an application queue managed by a BlazingMQ broker on a given machine looks like one of the following: <div class="fragment"><pre class="fragment">  bmq:<span class="comment">//ts.trades.myapp/my.queue</span>
  bmq:<span class="comment">//ts.trades.myapp.~bt/my.queue</span>
  bmq:<span class="comment">//ts.trades.myapp/my.queue?id=foo</span>
</pre></div> where: </dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
The URI scheme is always "bmq".  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
The URI authority is the name of BlazingMQ domain (such as  </li>
</ul>
"ts.trades.myapp") <div class="hanging"> </div></dd></dl>
<dl class="user"><dt><b></b></dt><dd><div class="hanging"> as registered with the BlazingMQ infrastructure. The domain name may</div></dd></dl>
<dl class="user"><dt><b></b></dt><dd><div class="hanging"> contain alphanumeric characters, dots and dashes (it has to match the</div></dd></dl>
<dl class="user"><dt><b></b></dt><dd><div class="hanging"> following regular expression: <code>[-a-zA-Z0-9\\._]+</code>). The domain may be</div></dd></dl>
<dl class="user"><dt><b></b></dt><dd><div class="hanging"> followed by an optional tier, introduced by the ".~" sequence and</div></dd></dl>
<dl class="user"><dt><b></b></dt><dd><div class="hanging"> consisting of alphanumeric characters and dashes. The ".~" sequence is</div></dd></dl>
<dl class="user"><dt><b></b></dt><dd><div class="hanging"> not part of the tier.</div></dd></dl>
<dl class="user"><dt><b></b></dt><dd><div class="hanging"> </div> </dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
The URI path is the name of the queue ("my.queue" above) and may contain alphanumeric characters, dashes, underscores and tild (it has to match the following regular expression: <code>[-a-zA-Z0-9_~\\.]+</code>). The queue name must be less than <code><a class="el" href="classbmqt_1_1Uri.html#a379cb043dab090426480866718fdc1a0">bmqt::Uri::k_QUEUENAME_MAX_LENGTH</a></code> characters long.  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
The name of the queue ("my.queue" above) may contain alphanumeric characters and dots.  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
<p class="startli">The URI may contain an optional query with a key-value pair. Currently supported keys are:</p>
<ul>
<li>
<b>id</b>: the corresponding value represents a name that will be used by BlazingMQ broker to uniquely identify the client.  </li>
</ul>
<p class="endli"></p>
</li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
The URI fragment part is currently unused.  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="usage_example_1"></a> <a class="anchor" id="description.usage_example_1"></a> <a class="anchor" id="3.2"></a> </dd></dl>
<dl class="user"><dt><b>Usage Example 1: </b></dt><dd>First, call the <code>initialize</code> method of the <code>UriParser</code>. This call is only needed one time; you can call it when your task starts. </dd></dl>
<dl class="user"><dt><b></b></dt><dd>Note that the <code>bmq</code> library takes care of that, so users of <code>bmq</code> don't have to explicitly do it themselves. <div class="fragment"><pre class="fragment">  <a class="code" href="structbmqt_1_1UriParser.html#a636751d810309e8335df0c8615ada41a">bmqt::UriParser::initialize</a>();
</pre></div> Then, parse a URI string created on the stack to populate a <code>Uri</code> object. The parse function takes an optional error string which is populated with a short error message if the URI is not formatted correctly. <div class="fragment"><pre class="fragment">   bsl::string input = <span class="stringliteral">&quot;bmq://my.domain/queue&quot;</span>;
   <a class="code" href="classbmqt_1_1Uri.html">bmqt::Uri</a>   uri(allocator);
   bsl::string errorDescription;

   <span class="keywordtype">int</span>         rc = <a class="code" href="structbmqt_1_1UriParser.html#a688ab161aebc54ecac04aba0ce13a373">bmqt::UriParser::parse</a>(&amp;uri, &amp;errorDescription, input);
   <span class="keywordflow">if</span> (rc != 0) {
      BALL_LOG_ERROR &lt;&lt; <span class="stringliteral">&quot;Invalid URI [error: &quot;</span> &lt;&lt; errorDescription &lt;&lt; <span class="stringliteral">&quot;]&quot;</span>;
   }
   assert(rc == 0);
   assert(error == <span class="stringliteral">&quot;&quot;</span>);
   assert(uri.scheme()    == <span class="stringliteral">&quot;bmq&quot;</span>);
   assert(uri.domain()    == <span class="stringliteral">&quot;my.domain&quot;</span>);
   assert(uri.queue()     == <span class="stringliteral">&quot;queue&quot;</span>);
</pre></div> </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="usage_example_2"></a> <a class="anchor" id="description.usage_example_2"></a> <a class="anchor" id="3.3"></a> </dd></dl>
<dl class="user"><dt><b>Usage Example 2: </b></dt><dd>Instantiate a <code>Uri</code> object with a string representation of the URI and an allocator. <div class="fragment"><pre class="fragment">  <a class="code" href="classbmqt_1_1Uri.html">bmqt::Uri</a> uri(<span class="stringliteral">&quot;bmq://my.domain/queue&quot;</span>, allocator);
  assert(uri.scheme() == <span class="stringliteral">&quot;bmq&quot;</span>);
  assert(uri.domain() == <span class="stringliteral">&quot;my.domain&quot;</span>);
  assert(uri.queue()  == <span class="stringliteral">&quot;queue&quot;</span>);
</pre></div> </dd></dl>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Thu Jun 15 2023 11:58:51 by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.1 </small></address>
</body>
</html>
